Propagation de Contexte Asynchrone en JavaScript : Suivi de Requêtes et Continuation avec AsyncLocalStorage

Dans le développement JavaScript moderne côté serveur, en particulier avec Node.js, les opérations asynchrones sont omniprésentes. La gestion de l'état et du contexte à travers ces frontières asynchrones peut être complexe. Cet article de blog explore le concept de propagation de contexte asynchrone, en se concentrant sur l'utilisation de AsyncLocalStorage pour réaliser efficacement le suivi des requêtes et la continuation. Nous examinerons ses avantages, ses limites et ses applications concrètes, en fournissant des exemples pratiques pour illustrer son utilisation.

Comprendre la Propagation de Contexte Asynchrone

La propagation de contexte asynchrone désigne la capacité à maintenir et à propager des informations de contexte (par exemple, les identifiants de requête, les détails d'authentification de l'utilisateur, les identifiants de corrélation) à travers les opérations asynchrones. Sans une propagation de contexte adéquate, il devient difficile de suivre les requêtes, de corréler les journaux et de diagnostiquer les problèmes de performance dans les systèmes distribués.

Les approches traditionnelles de gestion du contexte reposent souvent sur le passage explicite d'objets de contexte via des appels de fonction, ce qui peut conduire à un code verbeux et sujet aux erreurs. AsyncLocalStorage offre une solution plus élégante en fournissant un moyen de stocker et de récupérer des données de contexte au sein d'un unique contexte d'exécution, même à travers les opérations asynchrones.

Présentation d'AsyncLocalStorage

AsyncLocalStorage est un module intégré à Node.js (disponible depuis Node.js v14.5.0) qui offre un moyen de stocker des données locales à la durée de vie d'une opération asynchrone. Il crée essentiellement un espace de stockage qui est préservé à travers les appels await, les promesses et autres frontières asynchrones. Cela permet aux développeurs d'accéder et de modifier les données de contexte sans les passer explicitement.

Caractéristiques clés d'AsyncLocalStorage :

• Propagation de Contexte Automatique: Les valeurs stockées dans AsyncLocalStorage sont automatiquement propagées à travers les opérations asynchrones au sein du même contexte d'exécution.
• Code Simplifié: Réduit la nécessité de passer explicitement des objets de contexte via les appels de fonction.
• Observabilité Améliorée: Facilite le suivi des requêtes et la corrélation des journaux et des métriques.
• Sécurité des Threads (Thread-Safety): Fournit un accès thread-safe aux données de contexte au sein du contexte d'exécution actuel.

Cas d'Utilisation d'AsyncLocalStorage

AsyncLocalStorage est précieux dans divers scénarios, notamment :

• Suivi de Requêtes: Attribuer un identifiant unique à chaque requête entrante et le propager tout au long du cycle de vie de la requête à des fins de suivi.
• Authentification et Autorisation: Stocker les détails d'authentification de l'utilisateur (par ex., ID utilisateur, rôles, permissions) pour accéder aux ressources protégées.
• Journalisation et Audit: Joindre des métadonnées spécifiques à la requête aux messages de journal pour un meilleur débogage et audit.
• Surveillance des Performances: Suivre le temps d'exécution des différents composants au sein d'une requête pour l'analyse des performances.
• Gestion des Transactions: Gérer l'état transactionnel à travers plusieurs opérations asynchrones (par ex., les transactions de base de données).

Exemple Pratique : Suivi de Requêtes avec AsyncLocalStorage

Illustrons comment utiliser AsyncLocalStorage pour le suivi de requêtes dans une application Node.js simple. Nous allons créer un middleware qui attribue un identifiant unique à chaque requête entrante et le rend disponible tout au long du cycle de vie de la requête.

Exemple de Code

D'abord, installez les paquets nécessaires (si besoin) :

            npm install uuid express
            

              
                Copy
              
            
          

Voici le code :

            // app.js
const express = require('express');
const { AsyncLocalStorage } = require('async_hooks');
const { v4: uuidv4 } = require('uuid');

const app = express();
const asyncLocalStorage = new AsyncLocalStorage();
const port = 3000;

// Middleware pour attribuer un ID de requête et le stocker dans AsyncLocalStorage
app.use((req, res, next) => {
  const requestId = uuidv4();
  asyncLocalStorage.run(new Map(), () => {
    asyncLocalStorage.getStore().set('requestId', requestId);
    next();
  });
});

// Simuler une opération asynchrone
async function doSomethingAsync() {
  return new Promise(resolve => {
    setTimeout(() => {
      const requestId = asyncLocalStorage.getStore().get('requestId');
      console.log(`[Async] Request ID: ${requestId}`);
      resolve();
    }, 50);
  });
}

// Gestionnaire de route
app.get('/', async (req, res) => {
  const requestId = asyncLocalStorage.getStore().get('requestId');
  console.log(`[Route] Request ID: ${requestId}`);
  await doSomethingAsync();
  res.send(`Hello World! Request ID: ${requestId}`);
});

app.listen(port, () => {
  console.log(`App listening at http://localhost:${port}`);
});

            

              
                Copy
              
            
          

Dans cet exemple :

1. Nous créons une instance d'AsyncLocalStorage.
2. Nous définissons un middleware qui attribue un ID unique à chaque requête entrante en utilisant la bibliothèque uuid.
3. Nous utilisons asyncLocalStorage.run() pour exécuter le gestionnaire de requête dans le contexte de l'AsyncLocalStorage. Cela garantit que toutes les valeurs stockées dans l'AsyncLocalStorage sont disponibles tout au long du cycle de vie de la requête.
4. À l'intérieur du middleware, nous stockons l'ID de la requête dans l'AsyncLocalStorage en utilisant asyncLocalStorage.getStore().set('requestId', requestId).
5. Nous définissons une fonction asynchrone doSomethingAsync() qui simule une opération asynchrone et récupère l'ID de la requête depuis l'AsyncLocalStorage.
6. Dans le gestionnaire de route, nous récupérons l'ID de la requête depuis l'AsyncLocalStorage et l'incluons dans la réponse.

Lorsque vous exécutez cette application et envoyez une requête à http://localhost:3000, vous verrez l'ID de la requête journalisé à la fois dans le gestionnaire de route et dans la fonction asynchrone, démontrant que le contexte est correctement propagé.

Explication

• Instance AsyncLocalStorage : Nous créons une instance d'AsyncLocalStorage qui contiendra nos données de contexte.
• Middleware : Le middleware intercepte chaque requête entrante. Il génère un UUID, puis utilise asyncLocalStorage.run pour exécuter le reste de la chaîne de traitement de la requête *à l'intérieur* du contexte de ce stockage. C'est crucial ; cela garantit que tout ce qui suit a accès aux données stockées.
• asyncLocalStorage.run(new Map(), ...) : Cette méthode prend deux arguments : un nouveau Map vide (vous pouvez utiliser d'autres structures de données si approprié pour votre contexte) et une fonction de rappel. La fonction de rappel contient le code qui doit s'exécuter dans le contexte asynchrone. Toutes les opérations asynchrones initiées au sein de ce rappel hériteront automatiquement des données stockées dans le Map.
• asyncLocalStorage.getStore() : Ceci retourne le Map qui a été passé à asyncLocalStorage.run. Nous l'utilisons pour stocker et récupérer l'ID de la requête. Si run n'a pas été appelé, cela retournera undefined, c'est pourquoi il est important d'appeler run dans le middleware.
• Fonction Asynchrone : La fonction doSomethingAsync simule une opération asynchrone. Point crucial, même si elle est asynchrone (utilisant setTimeout), elle a toujours accès à l'ID de la requête car elle s'exécute dans le contexte établi par asyncLocalStorage.run.

Utilisation Avancée : Combinaison avec des Bibliothèques de Journalisation

L'intégration d'AsyncLocalStorage avec des bibliothèques de journalisation (comme Winston ou Pino) peut améliorer considérablement l'observabilité de vos applications. En injectant des données de contexte (par ex., ID de requête, ID utilisateur) dans les messages de journal, vous pouvez facilement corréler les journaux et suivre les requêtes à travers différents composants.

Exemple avec Winston

            // logger.js
const winston = require('winston');
const { AsyncLocalStorage } = require('async_hooks');

const asyncLocalStorage = new AsyncLocalStorage();

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.printf(({ timestamp, level, message }) => {
      const requestId = asyncLocalStorage.getStore() ? asyncLocalStorage.getStore().get('requestId') : 'N/A';
      return `${timestamp} [${level}] [${requestId}] ${message}`;
    })
  ),
  transports: [
    new winston.transports.Console()
  ]
});

module.exports = {
  logger,
  asyncLocalStorage
};

            

              
                Copy
              
            
          

            // app.js (modifié)
const express = require('express');
const { v4: uuidv4 } = require('uuid');
const { logger, asyncLocalStorage } = require('./logger');

const app = express();
const port = 3000;

app.use((req, res, next) => {
  const requestId = uuidv4();
  asyncLocalStorage.run(new Map(), () => {
    asyncLocalStorage.getStore().set('requestId', requestId);
    logger.info(`Incoming request: ${req.url}`); // Journaliser la requête entrante
    next();
  });
});

async function doSomethingAsync() {
  return new Promise(resolve => {
    setTimeout(() => {
      logger.info('Doing something async...');
      resolve();
    }, 50);
  });
}

app.get('/', async (req, res) => {
  logger.info('Handling request...');
  await doSomethingAsync();
  res.send('Hello World!');
});

app.listen(port, () => {
  logger.info(`App listening at http://localhost:${port}`);
});

            

              
                Copy
              
            
          

Dans cet exemple :

• Nous créons une instance de logger Winston et la configurons pour inclure l'ID de la requête depuis l'AsyncLocalStorage dans chaque message de journal. La partie clé est winston.format.printf, qui récupère l'ID de la requête (si disponible) depuis l'AsyncLocalStorage. Nous vérifions si asyncLocalStorage.getStore() existe pour éviter les erreurs lors de la journalisation en dehors d'un contexte de requête.
• Nous mettons à jour le middleware pour journaliser l'URL de la requête entrante.
• Nous mettons à jour le gestionnaire de route et la fonction asynchrone pour journaliser les messages en utilisant le logger configuré.

Désormais, tous les messages de journal incluront l'ID de la requête, ce qui facilitera le suivi des requêtes et la corrélation des journaux.

Approches Alternatives : cls-hooked et Async Hooks

Avant que AsyncLocalStorage ne soit disponible, des bibliothèques comme cls-hooked étaient couramment utilisées pour la propagation de contexte asynchrone. cls-hooked utilise les Async Hooks (une API Node.js de plus bas niveau) pour obtenir une fonctionnalité similaire. Bien que cls-hooked soit encore largement utilisé, AsyncLocalStorage est généralement préféré en raison de sa nature intégrée et de ses performances améliorées.

Async Hooks (async_hooks)

Les Async Hooks fournissent une API de plus bas niveau pour suivre le cycle de vie des opérations asynchrones. Bien que AsyncLocalStorage soit construit sur les Async Hooks, leur utilisation directe est souvent plus complexe et moins performante. Les Async Hooks sont plus appropriés pour des cas d'utilisation très spécifiques et avancés où un contrôle fin sur le cycle de vie asynchrone est requis. Évitez d'utiliser les Async Hooks directement, sauf en cas de nécessité absolue.

Pourquoi préférer AsyncLocalStorage à cls-hooked ?

• Intégré: AsyncLocalStorage fait partie du cœur de Node.js, éliminant le besoin de dépendances externes.
• Performance: AsyncLocalStorage est généralement plus performant que cls-hooked en raison de son implémentation optimisée.
• Maintenance: En tant que module intégré, AsyncLocalStorage est activement maintenu par l'équipe principale de Node.js.

Considérations et Limites

Bien que AsyncLocalStorage soit un outil puissant, il est important d'être conscient de ses limites :

• Limites du Contexte: AsyncLocalStorage ne propage le contexte qu'au sein du même contexte d'exécution. Si vous transmettez des données entre différents processus ou serveurs (par ex., via des files d'attente de messages ou gRPC), vous devrez toujours sérialiser et désérialiser explicitement les données de contexte.
• Fuites de Mémoire: Une utilisation incorrecte d'AsyncLocalStorage peut potentiellement entraîner des fuites de mémoire si les données de contexte ne sont pas correctement nettoyées. Assurez-vous d'utiliser asyncLocalStorage.run() correctement et évitez de stocker de grandes quantités de données dans l'AsyncLocalStorage.
• Complexité: Bien que AsyncLocalStorage simplifie la propagation du contexte, il peut également ajouter de la complexité à votre code s'il n'est pas utilisé avec précaution. Assurez-vous que votre équipe comprend son fonctionnement et suit les meilleures pratiques.
• Pas un Remplacement des Variables Globales: AsyncLocalStorage n'est *pas* un remplacement pour les variables globales. Il est spécifiquement conçu pour propager le contexte au sein d'une seule requête ou transaction. Une surutilisation peut conduire à un code fortement couplé et rendre les tests plus difficiles.

Meilleures Pratiques pour l'Utilisation d'AsyncLocalStorage

Pour utiliser efficacement AsyncLocalStorage, considérez les meilleures pratiques suivantes :

• Utiliser un Middleware: Utilisez un middleware pour initialiser l'AsyncLocalStorage et stocker les données de contexte au début de chaque requête.
• Stocker des Données Minimales: Ne stockez que les données de contexte essentielles dans l'AsyncLocalStorage pour minimiser la surcharge mémoire. Évitez de stocker de gros objets ou des informations sensibles.
• Éviter l'Accès Direct: Encapsulez l'accès à l'AsyncLocalStorage derrière des API bien définies pour éviter un couplage fort et améliorer la maintenabilité du code. Créez des fonctions d'aide ou des classes pour gérer les données de contexte.
• Considérer la Gestion des Erreurs: Mettez en œuvre une gestion des erreurs pour traiter élégamment les cas où l'AsyncLocalStorage n'est pas correctement initialisé.
• Tester Rigoureusement: Rédigez des tests unitaires et d'intégration pour vous assurer que la propagation du contexte fonctionne comme prévu.
• Documenter l'Utilisation: Documentez clairement comment AsyncLocalStorage est utilisé dans votre application pour aider les autres développeurs à comprendre le mécanisme de propagation de contexte.

Intégration avec OpenTelemetry

OpenTelemetry est un framework d'observabilité open-source qui fournit des API, des SDK et des outils pour collecter et exporter des données de télémétrie (par ex., traces, métriques, journaux). AsyncLocalStorage peut être intégré de manière transparente avec OpenTelemetry pour propager automatiquement le contexte de trace à travers les opérations asynchrones.

OpenTelemetry repose fortement sur la propagation de contexte pour corréler les traces entre différents services. En utilisant AsyncLocalStorage, vous pouvez vous assurer que le contexte de trace est correctement propagé au sein de votre application Node.js, vous permettant de construire un système de traçage distribué complet.

De nombreux SDK OpenTelemetry utilisent automatiquement AsyncLocalStorage (ou cls-hooked si AsyncLocalStorage n'est pas disponible) pour la propagation de contexte. Consultez la documentation de votre SDK OpenTelemetry choisi pour des détails spécifiques.

Conclusion

AsyncLocalStorage est un outil précieux pour gérer la propagation de contexte asynchrone dans les applications JavaScript côté serveur. En l'utilisant pour le suivi des requêtes, l'authentification, la journalisation et d'autres cas d'utilisation, vous pouvez construire des applications plus robustes, observables et maintenables. Bien que des alternatives comme cls-hooked et les Async Hooks existent, AsyncLocalStorage est généralement le choix préféré en raison de sa nature intégrée, de ses performances et de sa facilité d'utilisation. N'oubliez pas de suivre les meilleures pratiques et de tenir compte de ses limites pour exploiter efficacement ses capacités. La capacité de suivre les requêtes et de corréler les événements à travers les opérations asynchrones est cruciale pour construire des systèmes évolutifs et fiables, en particulier dans les architectures de microservices et les environnements distribués complexes. L'utilisation d'AsyncLocalStorage aide à atteindre cet objectif, conduisant finalement à un meilleur débogage, une meilleure surveillance des performances et une meilleure santé globale de l'application.